feat: History log logic for Components and Containers [FC-0123] by ChrisChV · Pull Request #38178 · openedx/openedx-platform

ChrisChV · 2026-03-16T23:19:04Z

Description

Publish history groups: Pre-Verawood vs Post-Verawood

The openedx-content library added a direct field to PublishLogRecord starting in the Verawood release (openedx/openedx-core#539). This field changes how publish history groups are structured, so the endpoint handles both eras:

Pre-Verawood (PublishLogRecord.direct is None): When a container and its components are published together, each entity produces its own independent group, even though they share the same publish_log_uuid. For example, publishing a Unit with 3 components creates 4 separate groups. Each group has scope_entity_key set to that specific entity's key, which the frontend must pass to the entries endpoint to fetch that entity's individual changes.

Post-Verawood (PublishLogRecord.direct is not None): The direct field marks which entities the user explicitly clicked "Publish" on (direct=True) vs. which were pulled in as side effects (direct=False, e.g. a shared component published from a sibling container). In this era, all entities from the same PublishLog are merged into a single group, and direct_published_entities lists only the explicitly published items. The scope_entity_key is null — the frontend uses the current container key to fetch entries.

This design means the frontend does not need era awareness: it always uses group.scope_entity_key ?? currentContainerKey when calling the entries endpoint.

Functions

Implements python api and REST_API functions to get the history log for a component:
- get_library_component_draft_history: Return the draft change history for a library component since its last publication.
- get_library_component_publish_history: Return the publish history of a library component as a list of groups.
- get_library_component_publish_history_entries: Return the individual draft change entries for a specific publish event.
- get_library_component_creation_entry: Return the creation entry (who created it and when).
Implements python api and REST_API functions to get the history log for containers:
- get_library_container_draft_history: Return the combined draft history for a container and all of its descendant components.
- get_library_container_publish_history: Return the publish history of a container as a list of groups.
- get_library_container_publish_history_entries: Return the individual draft change entries for the container entity in a specific publish event.
- get_library_container_creation_entry: Return the creation entry for a container.
Which edX user roles will this change impact? "Course Author", "Developer".

List of features (TODOs):

Supporting information

Github issue: Library: Object History Log frontend-app-authoring#2805
Depends on: feat: New history log api functions [FC-0123] openedx-core#501
Used in: feat: History log in content library components and containers [FC-0123] frontend-app-authoring#2948
Internal ticket: https://tasks.opencraft.com/browse/FAL-4330

Testing instructions

Follow the testing instructions in openedx/frontend-app-authoring#2948

Deadline

Before the Verawood cut.

Other information

N/A

openedx-webhooks · 2026-03-16T23:19:10Z

Thanks for the pull request, @ChrisChV!

This repository is currently maintained by @openedx/wg-maintenance-openedx-platform.

Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review.

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
- This process (including the steps you'll need to take) is documented here.
If it doesn't, simply proceed with the next step.

🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

Dependencies

This PR must be merged before / after / at the same time as ...
Blockers

This PR is waiting for OEP-1234 to be accepted.
Timeline information

This PR must be merged by XX date because ...
Partner information

This is for a course on edx.org.
Supporting documentation
Relevant Open edX discussion forum threads

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

Details

Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

The size and impact of the changes that it introduces
The need for product review
Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

rpenido · 2026-03-27T21:46:48Z

            path('assets/', blocks.LibraryBlockAssetListView.as_view()),
            path('assets/<path:file_path>', blocks.LibraryBlockAssetView.as_view()),
            path('publish/', blocks.LibraryBlockPublishView.as_view()),
+            # Get the draft change history for this block


Question: Can these endpoints be moved to xblock/rest_api and abstract the library logic?

I'm afraid no, but we will probably need to implement something like this there, for course xblocks, right?

I'm afraid there's no time to do it now; we can do it when this is implemented for the courses.

* Add get_library_container_publish_history and get_library_container_publish_history_entries to the containers API, returning groups (container + descendant components) sorted newest-first * Add entity_key field to LibraryPublishHistoryGroup so the frontend knows which entries endpoint to call per group; block_type is now nullable to support containers * Replace per-block publish_history/<uuid>/entries/ route with a single library-level publish_history_entries/ endpoint that accepts entity_key and publish_log_uuid as query params and routes to the correct handler

…s and scope_entity_key [FC-0123] Redesigns publish history groups to support the `direct` field on PublishLogRecord (added in Verawood). Key changes: - Replace `entity_key/title/block_type` in `LibraryPublishHistoryGroup` with `direct_published_entities: list[DirectPublishedEntity]`, each carrying `entity_key`, `title`, and `entity_type` (works for both components and containers). - Add `scope_entity_key: str | None` to each group so the frontend always knows which key to pass to the entries endpoint without needing era awareness (`group.scope_entity_key ?? currentContainerKey`). - Pre-Verawood (direct=None): one group per entity × publish event; `scope_entity_key` = that entity's key. - Post-Verawood (direct!=None): one merged group per PublishLog; `scope_entity_key` = null (frontend uses current container). - Rename `block_type` → `item_type` (non-nullable) in `LibraryHistoryEntry`; populate it for containers via `container_type.type_code` (e.g. "unit", "section"). - Rename entries query param `entity_key` → `scope_entity_key`. - Add Pre-Verawood and Post-Verawood integration tests.

ChrisChV · 2026-04-20T23:54:58Z

 openedx-atlas                       # CLI tool to manage translations
 openedx-calc                        # Library supporting mathematical calculations for Open edX
-openedx-core                        # Open edX Core: Content, Tagging, and other foundational APIs
+git+https://github.com/open-craft/openedx-learning.git@chris/FAL-4330-history-log#egg=openedx-core


TODO: Update this with the new version

…tions

ormsbee

I still have a lot more to review, but I wanted to submit this partial review before I turned in for today. Will look through this more in the morning.

ormsbee · 2026-04-23T22:33:43Z

+    Pre-Verawood groups have exactly one entry (approximated from available data).
+    Post-Verawood groups have one entry per direct=True record in the PublishLog.
+    """
+    entity_key: str          # str(usage_key) for components, str(container_key) for containers


Why make this a str instead of a LibraryUsageLocatorV2?

Updated: 43567d8

ormsbee · 2026-04-23T22:36:20Z

+    Pre-Verawood (direct=None): one group per entity × publish event.
+    Post-Verawood (direct!=None): one group per unique PublishLog.
+    """
+    publish_log_uuid: str


Similar above, why not have this be a UUID?

Updated: fab0165

ormsbee · 2026-04-23T22:38:09Z

+    # Pre-Verawood: the specific entity key for this group (container or usage key).
+    # Post-Verawood container groups: None — frontend must use currentContainerKey.
+    # Component history (all eras): str(usage_key).
+    scope_entity_key: str | None


Can this be a union of the acceptable key types?

Updated: 43567d8

ormsbee · 2026-04-23T22:52:20Z

+    Post-Verawood (direct!=None): one group per unique PublishLog.
+    """
+    publish_log_uuid: str
+    published_by: object  # AUTH_USER_MODEL instance or None


@kdmccormick: What's the right way to do this if we want to be respectful of custom user models? I vaguely recall you went down this rabbit hole once.

Actually, I think openedx-platform has too many assumptions about our user model for custom user models to work anyway, so maybe we can just make this a User?

Updated: 50355ee

ormsbee · 2026-04-24T00:33:27Z

+def resolve_contributors(users, request=None) -> list[LibraryHistoryContributor | None]:
+    """
+    Convert an iterable of User objects (possibly containing None) to a list of
+    LibraryHistoryContributor.


Please put more information in the docstring about how this function is expected to behave, such as:

What ordering guarantees does it make?

Will it remove duplicates?

Will it return None entries in the output?

Updated: 73ad2c9

ormsbee · 2026-04-24T00:48:54Z

+    ]
+
+
+def resolve_change_action(old_version, new_version) -> str:


Please annotate what types old_version and new_version are supposed to be.

Updated: cb03488

ormsbee · 2026-04-24T00:49:53Z

+    Returns "renamed" when both versions exist and the title changed between
+    them; otherwise returns "edited" as the default action.


Are creation and deletion out of scope?

Sorry I updated the code to return created and deleted entries in: cb03488

ormsbee · 2026-04-24T01:05:12Z

+    # Import here to avoid circular imports (container_metadata imports block_metadata).
+    from .container_metadata import library_container_locator  # noqa: PLC0415
+
+    title = record.new_version.title if record.new_version else ""


Does that mean that deletion is going to show up in the log as:

"" was edited

Because the new_version is going to be null?

Updated: 140a7c8

ormsbee · 2026-04-24T01:09:05Z

+    try:
+        component = record.entity.component
+        return DirectPublishedEntity(
+            entity_key=str(LibraryUsageLocatorV2(  # type: ignore[abstract]


Why is ignore[abstract] necessary?

LibraryUsageLocatorV2 implements all the abstract methods at runtime, but opaque_keys doesn't ship complete type stubs, so mypy can't verify the implementation and complains. The ignore is necessary here.

ormsbee · 2026-04-24T01:13:39Z

+            title=title,
+            entity_type=component.component_type.name,
+        )
+    except Component.DoesNotExist:


Please do checks with hasattr() for container vs. component, and branch accordingly. Having the container code path be an error handling fallback of component handling is awkward and will break when we have entities that are neither Components nor Containers.

Updated: 8ead067

…ypes

… resolve_contributor

ormsbee

Some more questions/suggestions on how LibraryHistoryContributor is handled.

ormsbee · 2026-04-24T20:22:36Z

+    """
+    One entry in the history of a library component.
+    """
+    changed_by: LibraryHistoryContributor | None


Everywhere else in the API, changed_by is a User, but here it's a new kind of object. What if we renamed changed_by to contributor to make that distinction clearer?

ormsbee · 2026-04-24T20:37:54Z

+    records = list(
+        content_api.get_entity_draft_history(component.publishable_entity)
+        .select_related("entity__component__component_type")
+    )
+    changed_by_list = resolve_contributors(
+        (record.draft_change_log.changed_by for record in records), request
+    )
+
+    entries = []
+    for record, changed_by in zip(records, changed_by_list, strict=False):
+        version = record.new_version if record.new_version is not None else record.old_version
+        entries.append(LibraryHistoryEntry(
+            changed_by=changed_by,
+            changed_at=record.draft_change_log.changed_at,
+            title=version.title if version is not None else "",
+            item_type=record.entity.component.component_type.name,
+            action=resolve_change_action(record.old_version, record.new_version),
+        ))
+    return entries


Could this be made into something like this?

draft_change_records = ( content_api.get_entity_draft_history(component.publishable_entity) .select_related( "entity__component__component_type", "draft_change_log__changed_by", ) ) entries = [] for record in draft_change_records: version = record.new_version if record.new_version is not None else record.old_version changed_by = record.draft_change_log.changed_by if changed_by: contributor = LibraryHistoryContributor.from_user(changed_by, request) else: contributor = None entries.append(LibraryHistoryEntry( contributor=contributor, changed_at=record.draft_change_log.changed_at, title=version.title if version is not None else "", item_type=record.entity.component.component_type.name, action=resolve_change_action(record.old_version, record.new_version), )) return entries

If caching is needed on the contributor construction, we could use a helper local fn like:

@cache # functools.cache def make_contributor(user): if user is None: return None return LibraryHistoryContributor.from_user(user, request) draft_change_records = ( content_api.get_entity_draft_history(component.publishable_entity) .select_related( "entity__component__component_type", "draft_change_log__changed_by", ) ) entries = [] for record in draft_change_records: version = record.new_version if record.new_version is not None else record.old_version entries.append(LibraryHistoryEntry( contributor=make_contributor(record.draft_change_log.changed_by), changed_at=record.draft_change_log.changed_at, title=version.title if version is not None else "", item_type=record.entity.component.component_type.name, action=resolve_change_action(record.old_version, record.new_version), )) return entries

…ublish history

…d_entity_from_record

feat: Python api and rest api added for component draft history

9e5a1c5

openedx-webhooks added the open-source-contribution PR author is not from Axim or 2U label Mar 16, 2026

ChrisChV marked this pull request as draft March 16, 2026 23:19

openedx-webhooks added this to Contributions Mar 16, 2026

github-project-automation Bot moved this to Needs Triage in Contributions Mar 16, 2026

ChrisChV changed the title ~~feat: Python api and rest api for History log logic~~ feat: Python api and rest api for History log logic [FC-0123] Mar 16, 2026

feat: publish history and entris functions added

80c9155

mphilbrick211 added the FC Relates to an Axim Funded Contribution project label Mar 23, 2026

mphilbrick211 moved this from Needs Triage to Waiting on Author in Contributions Mar 23, 2026

feat: Add profile images to contributors list

e20f0a3

This was referenced Mar 24, 2026

feat: History log in content library components and containers [FC-0123] openedx/frontend-app-authoring#2948

Open

feat: New history log api functions [FC-0123] openedx/openedx-core#501

Merged

ChrisChV added 3 commits March 24, 2026 18:28

feat: Add blockType to responses

0fdbd38

feat: get_library_component_creation_entry added

1688454

feat: get_library_container_draft_history function added

c6df70f

rpenido reviewed Mar 27, 2026

View reviewed changes

ChrisChV added 6 commits April 6, 2026 15:33

Merge branch 'master' into chris/FAL-4330-history-log

df20d13

fix: Broken lints

b0df5d3

Merge branch 'master' into chris/FAL-4330-history-log

e89065d

feat: Function to get creation entry for containers

bfc0013

ChrisChV changed the title ~~feat: Python api and rest api for History log logic [FC-0123]~~ feat: History log logic for Components and Containers [FC-0123] Apr 20, 2026

ChrisChV added 2 commits April 20, 2026 18:27

Merge branch 'master' into chris/FAL-4330-history-log

d0b6263

temp: Update openedx-core version

7cd6457

ChrisChV commented Apr 20, 2026

View reviewed changes

fix: Broken lints

cc87727

ChrisChV marked this pull request as ready for review April 21, 2026 02:16

ChrisChV requested a review from rpenido April 22, 2026 18:30

ChrisChV added 5 commits April 23, 2026 11:34

refactor: Add entity__component__component_type to history log func…

e9e9061

…tions

Merge branch 'master' into chris/FAL-4330-history-log

2518487

Merge branch 'master' into chris/FAL-4330-history-log

93be604

fix: Small fix in block_metadata about local_key

2345adf

fix: Broken lint and tests

8f7a67e

ormsbee requested changes Apr 24, 2026

View reviewed changes

ChrisChV added 9 commits April 24, 2026 13:17

chore: Update version of openedx-core

8f8019d

refactor: set entity_key and scope_entity_key as respective key t…

43567d8

…ypes

refactor: Set publish_log_uuid to UUID type

fab0165

refactor: Set published_by as AbstractUser

50355ee

style: Add comments

73ad2c9

refactor: simplify resolve_contributors body per code review

9f448b2

refactor: simplify prefetched lookup to use direct key access

438f959

refactor: move profile select_related to upstream querysets, simplify…

eedc9d0

… resolve_contributor

feat: handle created and deleted actions in resolve_change_action

cb03488

ormsbee requested changes Apr 24, 2026

View reviewed changes

ChrisChV added 2 commits April 24, 2026 15:44

fix: use old_version title as fallback for soft-deleted entities in p…

140a7c8

…ublish history

refactor: replace try/except with hasattr() checks in direct_publishe…

8ead067

…d_entity_from_record

		]


		def resolve_change_action(old_version, new_version) -> str:

		Returns "renamed" when both versions exist and the title changed between
		them; otherwise returns "edited" as the default action.

Conversation

ChrisChV commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Publish history groups: Pre-Verawood vs Post-Verawood

Functions

List of features (TODOs):

Supporting information

Testing instructions

Deadline

Other information

Uh oh!

openedx-webhooks commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ormsbee left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ormsbee left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

ChrisChV commented Mar 16, 2026 •

edited

Loading

openedx-webhooks commented Mar 16, 2026 •

edited

Loading